HTTP | Your Blog Name

HTTP 응답 코드 이해하기

HTTP 응답 코드는 서버가 클라이언트의 요청에 대해 어떤 결과가 있었는지 알려주는 3자리 숫자입니다. 이 코드는 백엔드 개발에서 매우 중요한 역할을 하며, 클라이언트와 서버 간의 HTTP 동작 결과를 소통합니다.

커스텀 에러 페이지: 많은 회사들이 404(페이지 없음), 403(접근 불가), 500(서버 오류) 등에서 서비스/브랜드에 맞춘 에러 페이지를 제공합니다. 이 페이지에는 회사 로고, 고객센터 안내, 홈으로 이동 링크 등이 포함될 수 있습니다.
구조화된 에러 응답: REST API 등에서는 응답 Body에 추가 정보를 담는 것이 일반적입니다.
- 애플리케이션 전용 에러 코드(USER_001 등)
- 상세한 에러 메시지
- 힌트나 해결 방법
- 프론트 또는 API 사용자가 프로그래밍적으로 처리할 수 있도록 에러 오브젝트/JSON 구조 제공
HTTP 상태 코드 확장/오버라이드:
- 표준 HTTP 상태 코드는 반드시 준수해야 하지만, 추가로 Custom Error Data를 응답에 실어 보낼 수 있습니다.
- 일부 시스템(balancer 등)은 백엔드 장애 시 커스텀 오류 페이지를 제공하도록 상태 코드를 오버라이드할 수 있습니다.
에러 코드별 맞춤 처리:
- 에러 유형, 클라이언트 요청, 엔드포인트, 인증 여부 등에 따라 응답을 커스터마이징
- 예: 401과 403을 구분해서 각각 다른 에러 메시지 또는 안내 제공

표준 코드 우선: 꼭 필요하지 않다면 표준 HTTP 코드 사용(상호 운용성과 명확함 확보). 커스텀 코드는 응답 Body 내부의 error code로만 활용.
일관된 구조 유지: API 전체에서 에러 응답 구조(예: JSON 내 code, message, details 등 필드)를 동일하게 관리
도움이 되는 메시지 제공: 에러 상세가 개발자나 사용자가 문제를 이해하고 해결할 수 있도록 안내해야 함.
보안 고려: 에러 메시지에 백엔드 내부 구조나 정보(예: Exception 또는 Stack Trace) 등은 노출하지 않기

{
  "status": 404,
  "error": "NOT_FOUND",
  "code": "USER_001",
  "message": "해당 ID의 사용자를 찾을 수 없습니다.",
  "details": "사용자 ID가 올바른지 확인하세요."
}

사용자용 커스텀 에러 페이지: 이커머스(쇼핑몰) 사이트에서 삭제된 상품 링크에 접속하면 "상품을 찾을 수 없습니다"와 함께 추천 상품이나 검색 창 제공
API 개발자용 에러 코드: 내부 마이크로서비스에서 커스텀 코드와 함께 구조화된 응답을 반환(로그 추적 및 디버깅 용이), 외부에는 표준 HTTP 코드(예: 400/404/500)만 노출
점검/다운타임 처리: 정기 점검 시, 로드밸런서에서 모든 요청에 대해 503이 아닌 브랜드화된 "점검중" 안내 페이지를 제공

표준 HTTP 상태 코드 전체와 베스트 프랙티스에 관해서는 공식 문서나 산업 가이드를 참고하는 것이 좋습니다.